//
//  "$Id: Flash.h 91860 2012-12-08 09:18:30Z li_weijun $"
//
//  Copyright (c)1992-2007, ZheJiang Dahua Technology Stock CO.LTD.
//  All Rights Reserved.
//
//	Description:	
//	Revisions:		Year-Month-Day  SVN-Author  Modification
//

#ifndef __RAW_FLASH_API_H__
#define __RAW_FLASH_API_H__

#include "Types.h"
#include "Defs.h"

#ifdef __cplusplus
extern "C" {
#endif

/// \defgroup RawFlashAPI API System
/// 原始flash设备直接操作接口，用于升级。
///	\n 调用流程图:
/// \code
///    ============================================
///                   |                            
///            createRawFlash                      
///                   |
///                (addRef)
///                   |
///                getCaps
///                   |                            
///         +---------|
///         |       read
///         |         |--------+
///         |       erase      |
///         |       write      |
///         |         |        |
///         +---------|--------+
///                   |         
///                release                       
///                   |                            
///    ============================================
/// \endcode
/// @{

typedef struct RawFlashCaps
{
	int type;			///< Flash类型，0-NAND，1-NOR，2-SPI
	int totalSize;		///< 总大小，字节为单位
	int sectorSize;		///< 扇区大小
	int reserved[29];	///< 保留
}RawFlashCaps;


///< 升级文件信息
typedef struct RawFlashFile
{
	char path[32];		///< 文件路径
	char filename[32];	///< 文件名
	char parttion[32];	///< 升级对像，如分区名，升级模块名，以install文件中的名字为准
	int reserved[64];   
}RawFlashFile;

typedef struct RawFlash
{
	/// 底层私有数据
	void *priv;


	/// 增加接口引用
	int (*addRef)(struct RawFlash *thiz);


	/// 释放接口
	int (*release)(struct RawFlash *thiz);


	/// 获取接口特性
	/// 
	/// \param [in] thiz flash接口指针
	/// \param [out] caps 接受flash接口特性结构RawFlashCaps指针
	/// \retval 0  获取成功
	/// \retval <0  获取失败
	int (*getCaps)(struct RawFlash *thiz, RawFlashCaps* caps);


	/// 读数据接口
	///
	/// \param [in] thiz flash接口指针
	/// \param [out] buf 数据缓冲的指针。
	/// \param [in] addr flash地址偏移，必须按扇区对齐。
	/// \param [in] len 要读出的字节数，必须按扇区对齐。
	/// \retval >0  读出的字节数
	/// \retval <=0 读失败
	int (*read)(struct RawFlash *thiz, char *buf, ulong addr, int len);


	/// 写数据接口，写数据之前底层会自动调用erase接口。
	/// 底层写入时可能是先读出来和新数据比较，如果不一致才写入。
	///
	/// \param [in] thiz flash接口指针
	/// \param [in] buf 数据缓冲的指针。
	/// \param [in] addr flash地址偏移，必须按扇区对齐。
	/// \param [in] len 要写入的字节数，必须按扇区对齐。
	/// \retval >0  写入的字节数
	/// \retval <=0 写失败
	int (*write)(struct RawFlash *thiz, char*buf, ulong addr, int len);


	/// 擦除数据接口，
	///
	/// \param [in] thiz flash接口指针
	/// \param [in] addr flash地址偏移，必须按扇区对齐。
	/// \param [in] len 要擦除的字节数，必须按扇区对齐
	/// \retval >0  擦除的字节数
	/// \retval <=0 擦除失败
	int (*erase)(struct RawFlash *thiz, ulong addr, int len);


	/// 中断flash操作，中断时写入的文件可能不完整，从而导致文件系统挂载失败。
	///
	/// \param [in] thiz flash接口指针
	/// \retval 0  中断成功
	/// \retval <0  中断失败
	int (*abort)(struct RawFlash *thiz);


	/// 写升级文件接口，写数据之前底层会自动调用erase接口。
	/// 底层写入时可能是先读出来和新数据比较，如果不一致才写入。
	///
	/// \param [in] thiz flash接口指针
	/// \param [in] flashFile 升级文件文件信息。
	/// \retval >0  写成功
	/// \retval <=0 写失败
	int (*writefile)(struct RawFlash *thiz, RawFlashFile* flashFile);

	/// 应用层完成所以数据写入后调用，通知底层升级已经完成。
	///
	/// \param [in] thiz flash接口指针
	/// \retval >0  写成功
	/// \retval <=0 写失败
	int (*complete)(struct RawFlash *thiz);
	
	/// 保留
	int reserved[118];
	
}RawFlash;

/// flash接口描述，128字节
typedef struct RawFlashDesc
{
	int index;					///< Flash芯片序号
	int reserved[31];			///< 保留
} RawFlashDesc;


/// 创建原始Flash设备接口。
///
/// \param [in] desc  flash接口描述结构RawFlashDesc指针
/// \param [out] flash flash接口指针的指针
/// \retval <0 创建失败
/// \retval 0 创建成功
int PAL_API createRawFlash(RawFlashDesc *desc, RawFlash **flash);


/// @} end of group

#ifdef __cplusplus
}
#endif

#endif //__RAW_FLASH_API_H__

